home *** CD-ROM | disk | FTP | other *** search
/ TOS Silver 2000 / TOS Silver 2000.iso / Anwendun / ARTHUR19 / MODULE / DEVELOP.TXT
Encoding:
Text File  |  1998-06-10  |  8.0 KB  |  207 lines
  1.  
  2.  
  3.  
  4.   Suchmodule für Arthur ab Version 1.8
  5.   Suchmodul-Formatbeschreibung
  6.  
  7.   Last Update: 10.06.1998
  8.  
  9. +---------------------------------------+----------------------------------------+
  10.  
  11. Ab Arthur 1.8 ist es ja nun möglich auch eigene Suchmodule einzubinden.
  12. Um dem geneigten Programmierer das Format der Module näher zu bringen, 
  13. soll dieser Text dienen.
  14.  
  15. Möglich wäre dann beispielsweise auch eine Nummernbibliothek mit dem zugehörigen
  16. Suchmodul. Das Bibliotheksformat bietet hierfür die Möglichkeit an, ein bestimmtes 
  17. namentliches Suchmodul vorzugsweise zu verwenden.
  18.  
  19. Übrigens:
  20. Wer ein Modul schreibt, daß mit intelligenter und lokaler Suche um 
  21. einiges schneller ist als die in Arthur eingebauten und es dem Arthur-Paket
  22. zur Verfügung stellt, bekommt Arthur für die Versandkosten =:)
  23.  
  24.  
  25. +---------------------------------------+----------------------------------------+
  26.  
  27.  
  28. Der Text ist in folgende Kapitel gegliedert:
  29.  
  30.  
  31.  1.0 · Richtlinien/Hinweise zum Modul
  32.  2.0 · Der Modul-Header
  33.  3.0 · Aufbau der Modul-Infostruktur
  34.  4.0 · Fehlercodes
  35.  5.0 · Übergabeparameter über den Stack
  36.  6.0 · Übergabe im Assembler-"Header"
  37.  7.0 · Vorhandene, anspringbare Routinen von Arthur
  38.  8.0 · Arthur-Bibliotheks-Format V1.8
  39.  
  40.  
  41.  
  42.  
  43.  
  44. +---------------------------------------+----------------------------------------+
  45. 1.0:  Modulhinweise:
  46. +---------------------------------------+----------------------------------------+
  47.    ~ Parameter werden nach Wunsch von Arthur über den Stack
  48.      oder über einen ASM-Header übergeben.
  49.    ~ Die Register werden von Arthur komplett gerettet.
  50.    ~ modale Dialogboxen, Zeichenfunktionen erlaubt (über-
  51.      gebenes VDI-Handle verwenden)
  52.    ~ Speicheranforderungen erlaubt, müssen aber vor Ende
  53.      freigegeben werden.
  54.    ~ Rücksprung nur mit rts.
  55.      (Das Modul wird als ein Unterprogramm von Arthur betrachtet.)
  56.    ~ die geladene Bibliothek ist auf Kompatibilität geprüft.
  57.    ~ die Buchstaben eines übergebenen Suchstrings sind bei 
  58.      Option "Groß/Klein egal" schon alle Groß.
  59.    ~ maximal 256 Ergebnisse
  60.  
  61.    ~ Hinweise zu den Rückgabeparametern (in D0): 
  62.  
  63.     · Anzahl Ergebnisse, wenn Suche erfolgreich.
  64.     · Bei einem Fehler sollte das Modul in D0 einen Zeiger auf 
  65.       einen nullterminierten Alertstring oder einen Fehlercode kleiner 0
  66.       (siehe Fehlercodes) zurückliefern. 
  67.     · Der Rückgabewert Null besagt, daß das Gesuchte nicht gefunden wurde.
  68.     · Anzahl durchsuchter Bibliothekseinträge als Long ab Buffer schreiben. 
  69.  
  70.  
  71.  
  72.    ~ Die Bibliotheksdaten dürfen natürlich nicht verändert werden.
  73.  
  74.  
  75.  
  76.  
  77.  
  78. +---------------------------------------+----------------------------------------+
  79. 2.0: Der Modul-Header
  80. +---------------------------------------+----------------------------------------+
  81.  
  82.   Der Modul-Header, der vor das Assemblierte Modul
  83.   gelinkt werden muss (64 Byte Länge):  
  84.   ================================================
  85.  Offset        Format        Wert    Beschreibung        
  86.  ------------------------------------------------------------    
  87.      00        Long        'AMOD'    Identifikation
  88.      04        Long        $0        reserviert        
  89.      08        Long        $0        reserviert        
  90.      12        Long        $FF2253    fest        
  91. FIX: 16        Long        ?         Datei-Offset ab Null auf eine Struktur zur
  92.                                      Modulinformation (Autor, Version..)        
  93.                                      oder Null.
  94.      20        Long        ?         Branch auf Suchroutine 
  95.                                      oder Null (dann nimmt Arthur die Adresse
  96.                                      des geladenen Moduls + Header als 
  97.                                      Unterprogrammadresse an).
  98.      24        Long        'V1.0'    Modulversion        
  99.      28        Word        ?         Bitvektor:
  100.  
  101.                      Bit        Beschreibung
  102.                      --------------------
  103.                      0        gesetzt = Modul Speicherresistent
  104.                      1        gesetzt = Werte über ASM-Header
  105.                                         (siehe ASM-Header)
  106.                      2        gesetzt = wind_update() setzen
  107.                      3        gesetzt = beg_update() setzen
  108.                      4        gesetzt = Maus auf "Busy" setzen.
  109.                               (kann aber auch das Modul machen).
  110.                      5-15     reserviert
  111.  
  112.      30-45    Byte        ?        gewünschter Popuptext (Nullterminiert)
  113.      46-63    Byte        ?        freier Text (Nullterminiert)
  114.  
  115.     Ggf. ist Nichtverwendetes mit Wert Null zu füllen.
  116.  
  117.  
  118.  
  119.  
  120.  
  121. +---------------------------------------+----------------------------------------+ 
  122. 3.0:  Modul-Infostruktur: 
  123. +---------------------------------------+----------------------------------------+
  124.  
  125.   Die Modul-Infostruktur dient zur Ausgabe einer Info über das Modul (Autor,
  126.   Modulversion etc.).
  127.   
  128.   Die Modul-Info wird aufgerufen, wenn ein Anwender im Popup-Menü einen
  129.   Eintrag mit Shift anwählt.
  130.  
  131.   Die Info kann sein:
  132.  
  133.     · Ein nullterminierter Alertstring, der dann von Arthur als Alert im Fenster  
  134.       dargestellt wird,
  135.     · oder etwas Eigenes (modal).
  136.  
  137.   Der Strukturaufbau als Alert:
  138.   -----------------------------
  139.   infostrukt:      dc.l -1        ; Alertstring
  140.                    dc.b '[1][Beispielinfo eines|Arthur-Suchmoduls][  OK  ],0
  141.  
  142.   Der Strukturaufbau bei Eigener Infodarstellung:
  143.   -----------------------------------------------
  144.   infostrukt:      dc.l infofunc  ; Branch auf Info-Routine (rts verwenden!)
  145.   (Die Register werden von Arthur gerettet)
  146.  
  147.  
  148.  
  149. +---------------------------------------+----------------------------------------+ 
  150. 4.0:  Fehlercodes: 
  151. +---------------------------------------+----------------------------------------+
  152.  
  153.       -39    nicht genügend Speicher
  154.      -107    fehlerhafte Bibliotheksdaten
  155.      -109    fehlerhafte Parameter
  156.      -110    fehlerhafte Bibliotheksadresse
  157.      -111    fehlerhafte Suchstringadresse
  158.      -112    fehlerhafte Bibliothek
  159.      -113    falsches Bibliotheksformat
  160.      -114    keine Grafikausgaben möglich
  161.      -115    unbekannter Fehler
  162.      -116    Suche nicht möglich
  163.  
  164.  
  165.  
  166. +---------------------------------------+----------------------------------------+
  167. 5.0:  Übergabeparameter:
  168. +---------------------------------------+----------------------------------------+
  169.  
  170.    Stackpos    Format    Beschreibung 
  171.    ------------------------------------------------------------
  172.      00    Long    Rücksprungadresse                
  173.      04    Word    ap_id von Arthur
  174.      06    Word    Arthur-VDI-Handle
  175.      08    Word    Bitvektor der Arthur-Suchoptionen:
  176.  
  177.                    Bit    Bedeutung
  178.                    -----------------
  179.                    0    Gross/Klein egal
  180.                    1    intelligente Suche
  181.                    2    Suchbeschränkung aktiv
  182.                    (im High-Byte steht dann die max. Ergebnisanzahl)
  183.  
  184.      10    Long    Adresse Arthur-Basepage
  185.      14    Long    Adresse Bibliothek
  186.      18    Long    Adresse eines 512 Bytes großen, frei nutzbaren Buffers ab 
  187.                    dessen Anfang der Suchstring steht.
  188.      22    Word    Länge des Suchstrings     
  189.      24    Long    Adresse Ergebnispointerspeicher (256 * 4 Longs)
  190.      28    Long    Adresse der Decodier-Routine (siehe decode-Aufruf)
  191.      32    Long    Adresse der String-Exist-Routine (siehe string_exist-Aufruf)
  192.      36    Long    Adresse der Upper-Routine (siehe upper-Aufruf)
  193.  
  194.  
  195.  
  196.  
  197.  
  198. +---------------------------------------+----------------------------------------+ 
  199. 6.0:  Übergabe über einen Assembler-"Header":
  200. +---------------------------------------+----------------------------------------+
  201.      Wie übergabeparameter, nur ID 'ASMP' ersetzt die Rücksprungadresse.
  202.      Auf dem Stack steht dann nur die Rücksprungadresse.
  203.  
  204.      Sinn dieser Möglichkeit ist die Übergabe der Parameter in schon
  205.      festgelegte Variablen, die am Anfang des Programmes deklariert sind
  206.      (z.Bsp. mit EQU). Die Parameter werden dann nicht über den Stack 
  207.      übergeben, so